home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / program / tjgold.zip / INSTALL.004 / FGUSER06.TXT < prev    next >
Text File  |  1995-05-29  |  15KB  |  403 lines
  1.                          Directory & File Selection
  2.  
  3.                                  "As a jewel of gold in a swines snout,
  4.                                   so is a fair woman which is without
  5.                                   discretion"
  6.                                                          Proverbs 11.22
  7.  
  8. Introduction
  9.  
  10.           The GOLDDIR unit includes a set of customizable dialogs which
  11.      perform the following duties:
  12.  
  13.           Displays a file open/close dialog with files, directories,
  14.      drives and file masks listed à la Windows.
  15.  
  16.           Displays a multi-column list of files (and optionally
  17.      directories/drives) allowing the user to select a file.
  18.  
  19.           Displays a Directory Selector/Changer dialog to allow the user
  20.      to navigate around drives and directories.
  21.  
  22.  
  23. Figure 6.1
  24. The PromptFile dialog
  25.  
  26. Using PromptFile to Choose a File
  27.  
  28.      The PromptFile function in GOLDDIR is defined as follows:
  29.  
  30.      PromptFile(FullFilename:PathStr): StrScreen;
  31.  
  32.           Displays a file selection dialog allowing the user to enter an
  33.      explicit filename or to navigate around the drives and directories
  34.      and select a file from the list. The only parameter is a string
  35.      that specifies the default mask/filename that will be displayed in
  36.      the Filename field when the dialog is first displayed. If the
  37.      string includes a path, the dialog will fill the directory and
  38.      drive list with the specified path as the current selection.
  39.  
  40.           The function returns the fully qualified filename of the
  41.      selected file, or a null string if the user escaped/cancelled.
  42.  
  43.           The demo file DEMDIR1.PAS shows how easily a file dialog can
  44.      be displayed. (See figure 6.1).
  45.  
  46. Adding Custom Help
  47.  
  48.           By default, the PromptFile dialog does not include a help
  49.      button. However, a help button will automatically appear (as if by
  50.      magic) when you use the following procedure:
  51.  
  52.      AssignDirHelpHook(PFHook: PromptHelpHook);
  53.  
  54.           Assigns a help procedure to a PromptFile or PromptDir dialog.
  55.      The passed procedure must be declared far and have no passed
  56.      parameters.
  57.  
  58.           The hooked procedure will be called whenever the user selects
  59.      the Help button. To subsequently remove the Help button, call the
  60.      procedure RemoveDirhelpHook before displaying the dialog.
  61.  
  62.           Run DEMDIR2.PAS (or DEMDIR6.PAS) for a demonstration of the
  63.      custom help facility.
  64.  
  65. Ensuring a File Exists
  66.  
  67.           Users can manually enter a filename in the filename field of
  68.      the dialog, rather than selecting from the list of files. You can
  69.      ensure the user only enters the name of an existing file by setting
  70.      the value of DirsVars.ExistOnly to true. If the user tries to enter
  71.      a file which does not exist, an error message is displayed and the
  72.      user is returned to the dialog.
  73.  
  74. Customizing  the PromptFile Dialog
  75.  
  76.           By default, the PromptFile dialog is constructed as a file
  77.      open dialog. However, the window title, button text and button
  78.      hotkeys can all be customized to change the flavor of the dialog.
  79.      International developers can easily change all the dialog text and
  80.      messages to a different language.
  81.  
  82.           The DirVars record variable includes the following variables
  83.      which influence the displayed text:
  84.  
  85. Changing the Window Title
  86.  
  87.           The following variable controls the window title, and defaults
  88.      to 'Pick a File':
  89.  
  90.      DirVars.StrPromptFileTitle: string[60];
  91.  
  92. Changing the Buttons
  93.  
  94.           Both the text and the associated hot key of each of the three
  95.      buttons may be changed by modifying the following variables:
  96.  
  97.      DirVars.OpenButStr: strbutton;
  98.      DirVars.OpenHK: word;
  99.      DirVars.CancelButStr: strbutton;
  100.      DirVars.CancelHK: word;
  101.      DirVars.HelpButStr: strbutton;
  102.      DirVars.HelpHK: word;
  103.  
  104.      The defaults for these variables are as follows:
  105.  
  106.            OpenButStr := '  ~O~pen  ';
  107.            CancelButStr := ' ~C~ancel ';
  108.            HelpButStr := '  ~H~elp  ';
  109.            OpenHK := 280;
  110.            CancelHK := 302;
  111.            HelpHK := 291;
  112.  
  113.           Run the demo DEMDIR3.PAS to see a custom Save As dialog that
  114.      was developed by modifying the buttons and title.
  115.  
  116. Changing Error Dialogs
  117.  
  118.           When the user selects a drive which is not available or ready
  119.      (e.g. when the user selects a floppy drive when no disk is in the
  120.      drive), Gold displays an error dialog. The error title and text can
  121.      be customized by modifying the following variables:
  122.  
  123.      DirVars.NotReadyTitle: string [30];
  124.      DirVars.NotReadyMsgA: string [30];
  125.      DirVars.NotReadyMsgB: string [60];
  126.  
  127.      The default text for these variables is as follows:
  128.  
  129.      NotReadyTitle := 'Drive not ready!';
  130.      NotReadyMsgA := 'Cannot read drive ';
  131.      NotReadyMsgB := 'Please insert a disk or select Cancel';
  132.  
  133.           When a user enters the name of a file which does not exist,
  134.      and DirVars. ExistsOnly is set to true, an error is displayed. The
  135.      error title and text can be customized by modifying the following
  136.      variables:
  137.  
  138.      DirVars.NoExistTitle: string [30];
  139.      DirVars.NoExistText: string [60];
  140.  
  141.      The default text for these variables is as follows:
  142.  
  143.      NoExistTitle := ' INVALID ';
  144.      NoExistText := '||^Not a valid path or file name';
  145.  
  146. Customizing PromptFile Colors
  147.  
  148.           If (for some inexplicable reason) you have the urge to change
  149.      the default colors used in the file dialog, read on. If you are not
  150.      familiar with Gold's Tint system, read the section Customizing
  151.      Display Colors in Chapter 3 before proceeding.
  152.  
  153.           When changing the colors, it helps to realize that the dialog
  154.      is actually an IO form (yes we use our own tools) and many of the
  155.      colors are modified by altering the default IO colors.
  156.  
  157.           Listed below is an extract from the demo file DEMDIR4.PAS
  158.      which customizes every component of the dialog:
  159.  
  160.      procedure CustomizeColors;
  161.      {}
  162.      begin
  163.         {first the window border}
  164.         GoldSetColor(IOWinTitle,WhiteonMagenta);
  165.         GoldSetColor(IOWinIcons,GreenonMagenta);
  166.         GoldSetColor(IOWinBorder1,YellowonMagenta);
  167.         GoldSetColor(IOWinBody,YellowonMagenta);
  168.         {now the buttons}
  169.         GoldSetColor(IOButtonNormHot,WhiteOnBlue);
  170.         GoldSetColor(IOButtonNorm,YellowOnBlue);
  171.         GoldSetColor(IOButtonHiHot,WhiteonRed);
  172.         GoldSetColor(IOButtonHi,YellowOnRed);
  173.         {now the list fields}
  174.         GoldSetColor(ListHi1,WhiteOnRed);
  175.         GoldSetColor(ListNorm1,LightcyanOnBlue);
  176.         GoldSetColor(ListScrollBarHi,LightcyanOnBlue);
  177.         {and finally the messages}
  178.         GoldSetColor(IOLabelNorm,CyanOnMagenta);
  179.         GoldSetColor(IOLabelHi,LightcyanOnMagenta);
  180.      end; { CustomizeColors }
  181.  
  182. Using PromptDir to Choose a Directory
  183.  
  184.           If you want to get the user to select a directory, use
  185.      PromptDir as follows:
  186.  
  187.      PromptDir(FullFilename:PathStr;Cmt:StrScreen): StrScreen;
  188.  
  189.           Displays a directory selection dialog allowing the user to
  190.      navigate around the drives and directories and select a path. The
  191.      first parameter is a string that specifies the default path that
  192.      will be selected when the dialog is first displayed. The second
  193.      parameter is an optional comment which will be inserted at the top
  194.      of the dialog. If the user escapes, a null string is returned,
  195.      otherwise the selected directory (fully-qualified) is returned.
  196.  
  197.           Like PromptFile, PromptDir supports a custom help button when
  198.      the procedure AssignDirHelpHook is used to assign a custom help
  199.      procedure.
  200.  
  201.           Run the demos DEMDIR3.PAS and DEMDIR4.PAS to see PromptDir in
  202.      action. (See Figure 6.2)
  203.  
  204. Customizing  the PromptDir Dialog
  205.  
  206.           The window title, button text and button hotkeys can all be
  207.      customized to change the flavor of the dialog. International
  208.      developers can easily change all the dialog text and messages to a
  209.      different language.
  210.  
  211.           The DirVars record variable includes the following variables
  212.      which influence the displayed text:
  213.  
  214. Changing the Window Title
  215.  
  216.           The following variable controls the window title and defaults
  217.      to 'Change directory' :
  218.  
  219.      DirVars.StrPromptDirTitle : string[60];
  220.  
  221.      Figure 6.2
  222.      The PromptDir dialog
  223.  
  224.  
  225. Changing the Buttons
  226.  
  227.           Both the text and the associated hot key of each of the three
  228.      buttons may be changed by modifying the following variables:
  229.  
  230.      DirVars.OKButStr: strButton;
  231.      DirVars.OKHK: word;
  232.      DirVars.CancelButStr: strbutton;
  233.      DirVars.CancelHK: word;
  234.      DirVars.HelpButStr: strbutton;
  235.      DirVars.HelpHK: word;
  236.  
  237.      The defaults for these variables are as follows:
  238.  
  239.            OKButStr := '   ~O~K   ';
  240.            CancelButStr := ' ~C~ancel ';
  241.            HelpButStr := '  ~H~elp  ';
  242.            OKHK := 280;
  243.            CancelHK := 302;
  244.            HelpHK := 291;
  245.  
  246.           The error text for error dialogs can be changed in the manner
  247.      described in the section Changing Error Dialogs on page 6-3.
  248.  
  249. Customizing PromptDir Colors
  250.  
  251.           The technique for customizing the PromptDir colors is similar
  252.      to PromptFile (discussed earlier). Listed below is an extract of
  253.      the demo program DEMDIR7.PAS which assigns custom colors to the
  254.      dialog.
  255.  
  256.      procedure CustomizeColors;
  257.      {}
  258.      begin
  259.         {first the window border}
  260.         GoldSetColor(IOWinTitle,WhiteonMagenta);
  261.         GoldSetColor(IOWinIcons,GreenonMagenta);
  262.         GoldSetColor(IOWinBorder1,YellowonMagenta);
  263.         GoldSetColor(IOWinBody,YellowonMagenta);
  264.         {now the buttons}
  265.         GoldSetColor(IOButtonNormHot,WhiteOnBlue);
  266.         GoldSetColor(IOButtonNorm,YellowOnBlue);
  267.         GoldSetColor(IOButtonHiHot,WhiteonRed);
  268.         GoldSetColor(IOButtonHi,YellowOnRed);
  269.         {now the list fields}
  270.         GoldSetColor(ListHi1,WhiteOnRed);
  271.         GoldSetColor(ListNorm1,LightcyanOnBlue);
  272.         GoldSetColor(ListScrollBarHi,LightcyanOnBlue);
  273.         {and finally the messages}
  274.         GoldSetColor(IOLabelNorm,CyanOnMagenta);
  275.         GoldSetColor(IOLabelHi,LightcyanOnMagenta);
  276.      end; { CustomizeColors }
  277.  
  278. Using FileList to a Choose File
  279.  
  280.           FileList takes advantage of Gold's list management tools and
  281.      displays a list of files in a multi-column list (see Figure 6.3).
  282.  
  283.      Run the demo file DEMDIR8.PAS to see FileList in action.
  284.  
  285.           To display a file list in a stretchable window call FileList
  286.      which is defined as follows:
  287.  
  288.      FileList(FullFilename:PathStr; Tit:StrScreen): StrScreen;
  289.  
  290.           Displays a list of files in a list window. The first string
  291.      parameter identifies the filemask. If the string includes a path,
  292.      the path will be the start-up directory when the window is first
  293.      displayed. The second parameter is an optional title.
  294.  
  295.           The function returns the fully-qualified filename of the
  296.      selected file, or a null string if the user escaped.
  297.  
  298.      Figure 6.3
  299.      The FileList window
  300.  
  301.  
  302.           FileList can display multiple file masks in a single list. All
  303.      you have to do is specify multiple filemasks in the Fullfilename
  304.      parameter. Try passing the string '*.pas *.asm *.inc'. You can
  305.      still specify a full-qualified path on the first mask, e.g.
  306.      'c:\stuff\*.pas *.asm *.inc'. This technique will also work with
  307.      the PromptFile command.
  308.  
  309. Sorting the File List
  310.  
  311.           DirVars includes the boolean variable SortByName. If this
  312.      variable is set to TRUE (the default being FALSE), Gold will sort
  313.      the files in name order.
  314.  
  315. Changing Informational Text
  316.  
  317.           Information about the highlighted file is displayed in a two
  318.      line panel at the bottom of the window (see figure 7-2). The
  319.      DirVars record variable includes the following variables which
  320.      influence the text displayed in the panel:
  321.  
  322.      DirVars.ParentStr: string[30];
  323.  
  324.           The string displayed when the highlight bar is on the '..'
  325.      file. The default string is 'Parent directory'.
  326.  
  327.      DirVars.SubDirStr: string[30];
  328.  
  329.           The string which is a prefix to a sub-directory name when a
  330.      sub-directory is highlighted. The default string is 'Sub
  331.      directory'.
  332.  
  333.      DirVars.RootStr: string[30];
  334.  
  335.           The string displayed when the highlight bar is on the
  336.      '\ (root)' file. The default string is 'Root directory'.
  337.  
  338.      DirVars.NoFilesStr: string[30];
  339.  
  340.           The string displayed when no matching files are encountered in
  341.      the active directory.
  342.  
  343.      DirVars.RootNameStr: string[12];
  344.  
  345.           The "filename" of the list entry which, when selected, jumps
  346.      the user to the root of the active drive. The default name is '\
  347.      (root)'.
  348.  
  349.      DirVars.DriveStr: string[20];
  350.  
  351.           The string which is a prefix to a drive letter when a drive is
  352.      highlighted. The default string is 'Drive'.
  353.  
  354.      DirVars.SortingStr: string[30];
  355.  
  356.           The message string which is displayed at the top-left of the
  357.      list window when Gold is sorting the filename list. The default
  358.      string is 'Sorting files...'.
  359.  
  360.           Run the demos DEMDIR8.PAS through DEMDIR11.PAS for examples of
  361.      customizing the FileList display.
  362.  
  363. Customizing the FileList Display Colors
  364.  
  365.           The display colors used by FileList are controlled by setting
  366.      the defaults in GOLDTINT. The demo file DEMDIR12.PAS illustrate how
  367.      to customize all the display colors used by FileList. Listed below
  368.      is an extract from this demo file:
  369.  
  370.      procedure CustomizeColors;
  371.      {}
  372.      begin
  373.         {first the window border}
  374.         GoldSetColor(ListTitle,WhiteonMagenta);
  375.         GoldSetColor(ListIcons,LightgrayOnMagenta);
  376.         GoldSetColor(ListBorder1,YellowonMagenta);
  377.         GoldSetColor(ListBorder2,BlackonMagenta);
  378.         GoldSetColor(ListNorm1,BlackonMagenta);
  379.         {now the list fields}
  380.         GoldSetColor(ListNorm1,YellowOnMagenta);  {files}
  381.         GoldSetColor(ListHi1,WhiteOnCyan);
  382.         GoldSetColor(ListNorm2,WhiteOnMagenta);
  383.         {directories and drives}
  384.         GoldSetColor(ListHi2,BlackOnCyan);
  385.         GoldSetColor(ListScrollBarHi,LightgrayOnMagenta);
  386.         {now the file info}
  387.         GoldSetColor(DirListInfo,LightgrayonMagenta);
  388.      end; { CustomizeColors }
  389.  
  390.  
  391. Error Handling
  392.  
  393.           All the directory and file displaying functions discussed in
  394.      this chapter have the potential to fail. For example, there may be
  395.      insufficient memory to display all the files. After calling one of
  396.      the functions, always call the function LastDirError to see if the
  397.      operation was successful.
  398.  
  399.           One final note. If you want to display a list of files and
  400.      allow the user to select multiple files, create a custom list using
  401.      the RunList command. This technique is explained in Chapter 14 and
  402.      can be viewed in the demo file DEMLS4.PAS.
  403.